Release 10.1A: OpenEdge Development:
Web Services

Managing asynchronous requests

As indicated previously, you can invoke Web service requests asynchronously from the 4GL. This means that you can invoke a Web service request in such a way that the result is handled independently of the mainline flow of execution. That is, 4GL statements following the asynchronous request execute immediately and in order without waiting for the result of the asynchronous request to be available. Instead, the asynchronous request specifies an internal event procedure to handle the result when the result for that asynchronous request becomes available, which is signalled by the activation of a PROCEDURE-COMPLETE event.

When it is time to handle the PROCEDURE-COMPLETE event, the specified event procedure executes and manages any OUTPUT or INPUT-OUTPUT parameters that were passed to the asynchronous request when it was invoked. These parameters are returned as INPUT parameters to the event procedure, which can store the parameter values or otherwise process the result for use by the mainline program. The mainline program can periodically inspect an asynchronous request object handle (also available to the event procedure), which it sets during invocation of the request, in order to determine if the specified asynchronous request has completed. If the request has completed, the program can then make use of the results as provided by the internal event procedure that handled them.

The model for asynchronous Web service request invocation is very similar to the model for asynchronous remote procedure invocation on a session-free AppServer. This section describes the asynchronous Web service calling model, noting any differences from the asynchronous session-free AppServer calling model. For information on the model for invoking asynchronous requests on a session-free AppServer, see OpenEdge Application Server: Developing AppServer Applications .

Note: For certain features that support Web service requests in the 4GL (for example, error handling), the feature behavior might differ depending on whether the request is synchronous or asynchronous. The documentation describes these differences in the chapters where the features are described.

Supported asynchronous Web service requests

You can only invoke an asynchronous Web service request as a procedure using the RUN statement. This means that if a Web service operation is invoked as a user-defined function, you can only invoke it synchronously, because all operations that have a return value can only be invoked as user-defined functions, where the value must be made available at the point of invocation. This is consistent with how OpenEdge supports the invocation of asynchronous requests on the AppServer (remote procedures only).

Order of completion

Similar to a session-free AppServer request, the order of completion for an asynchronous Web service request is determined solely by the Web service. The manner in which the 4GL client send and response queues for an asynchronous request handle messages is identical for both session-free asynchronous AppServer requests and asynchronous Web service requests. That is, if the 4GL invokes multiple asynchronous Web service requests, the order of their completion cannot be determined on the Web service or session-free AppServer client. So, you must write your mainline program, and indeed your asynchronous event procedures, to make no assumptions about the order in which multiple asynchronous Web service requests complete.

A subtle distinction between a session-free asynchronous AppServer request and an asynchronous Web service request is the SOAP response callback procedure available for the Web service request (see the "Handling the information in SOAP headers" section). If a SOAP response callback procedure is set for an asynchronous Web service request, it executes after the SOAP response message arrives at the client but before the asynchronous event procedure executes to handle the PROCEDURE-COMPLETE event for the request.

Asynchronous request object handle

OpenEdge maintains an asynchronous request object for each asynchronous request, which maintains the status of the request, including whether and how it has completed (successfully or unsuccessfully). The handle to this asynchronous request object is available to the mainline program and to the event procedure for an asynchronous Web service request in the same way as for an asynchronous AppServer request. The Web service server object handle maintains its own chain of pending asynchronous request object handles (FIRST-ASYNC-REQUEST and LAST-ASYNC-REQUEST attributes), and the PROCEDURE-NAME attribute on each asynchronous request object handle returns the name of its Web service operation as it returns the name of the remote procedure executed for an asynchronous AppServer request.

Table 1–3 shows attributes on the asynchronous object handle with special meaning for Web services.

Table 1–3: Attributes on Web service asynchronous request object handle 

Attribute	Meaning for Web service requests
ERROR	Returns TRUE within the context of the event procedure when: You invoke the RETURN ERROR statement within the context of an associated SOAP response header callback procedure. A SOAP fault is returned for the asynchronous Web service request.
NEXT-SIBLING and PREV-SIBLING	Maintains a chain of asynchronous request object handles for all pending asynchronous requests invoked in the same Web service.
PERSISTENT-PROCEDURE	Returns a handle to the procedure object bound to the Web service port type.
PROCEDURE-NAME	Returns the name of the Web service operation invoked asynchronously.
QUIT	Always returns FALSE for an asynchronous Web service request.
SERVER	Returns a handle to the server object for the Web service where the asynchronous request is executed.

Results handling

A few differences exist in the results returned for an asynchronous Web service request compared to an asynchronous AppServer request, as shown in Table 1–4.

Table 1–4: Results for asynchronous Web service requests 

4GL result elements	Web service request result
ERROR-STATUS system handle	If the ERROR attribute of the asynchronous request object handle is set to TRUE because of a SOAP fault, the ERROR-STATUS:ERROR-OBJECT-DETAIL attribute references a SOAP fault object with information on the SOAP fault (see the "Handling Web service errors" section).
RETURN-VALUE function	The value for 4GL RETURN-VALUE function is never altered directly by the response from a Web service asynchronous request.
STOP condition	The client can raise the STOP condition by executing the CANCEL-REQUESTS( ) method on the Web service server object handle. All outstanding Web service requests are handled in a similar manner to those on an AppServer, except that for any currently executing Web service requests, the result is undefined. OpenEdge disconnects from all ports to currently executing Web service requests, and the exact response depends on how the Web service responds to the lost connection.